Skip to content

fix(update): require qualified defaults for runtime previews - #9026

Closed
loopx-agent wants to merge 1 commit into
mainfrom
codex/runtime-preview-adoption-20261118
Closed

loopx-agent wants to merge 1 commit into
mainfrom
codex/runtime-preview-adoption-20261118

Conversation

@loopx-agent

Copy link
Copy Markdown
Collaborator

Problem

The published runtime-main descriptor for 65ae1d6ec05d0594947a7a47e1e2fc7d7b304e86 lacks a default_contract. The hosted bootstrap installed its verified archive into an isolated environment. The installed quota CLI then reported the complete_turn writer. Producer validation in #9018 covers new snapshots. The current installer also needs to handle already published preview descriptors. Published preview channel

Change

The existing manifest validator requires a supported default contract when the CLI or website bootstrap selects a preview for installation. The installer repeats the same check for a previously resolved descriptor and compares the archived contract with the descriptor. Historical metadata stays readable. An archived stable release with matching legacy metadata remains installable, and installed releases retain their existing rollback path.

Validation

  • The standalone bootstrap built from 6a9894c6909da64c97f4da39ad15ee343b344514 rejected the actual moving preview and its pinned revision before archive download. The preview attempts preserved the installed CLI and made no additions to the download cache.
  • The same standalone bootstrap installed published stable 2.3.0 from its legacy descriptor. The installed quota CLI reported the supported quota_packet writer and installation Doctor passed after both preview rejections.
  • On macOS arm64, the exact committed CLI source reported the live preview blocked during both update plan and update apply. The apply attempt with explicit downgrade intent left the installed release in place.
  • The focused suites passed 196 tests with 3 skips. All 6 direct and 19 selected standard premerge checks passed.
  • The existing Pages workflow exports this installer source. Deployment and coverage on other platforms remain pending.

Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>

@loopx-agent loopx-agent left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewer: model_agent · Gemini · Google (self_reported; host runtime observation unavailable)

Approval conclusion (author-owned PR; GitHub blocks formal self-approval)

本次针对 PR #9026 的精确提交 6a9894c6909da64c97f4da39ad15ee343b344514 完成源码走读、双版本(基线 4a0188c1ca1b6e33a11a7e31ddb56315bc1cdd46 与当前 HEAD 6a9894c6909da64c97f4da39ad15ee343b344514)反事实对比探针、单元测试、架构测试及 premerge 门禁验证。结论:无阻断性问题(no blocking findings),建议 APPROVE(因作者与当前登录审查账号同为 PR 所属方,按规则以 COMMENTED 评审发布批准结论,且不执行合并或删分支操作)。

动机 / Motivation

通过独立引导脚本 scripts/install-from-github.sh(下载 update-artifact.py)安装预览运行时,或运行 loopx update check、loopx update plan、loopx update apply、loopx upgrade 更新 release snapshot(含 --ref main 与固定 40 位提交 SHA)的维护者与开发者。

此前虽然 PR #9018 已拦截新构建的未达标 main 快照发布,但此前已发布的 runtime-main 历史描述符(对应提交 65ae1d6)缺少 default_contract 字段。改动前 validate_manifest 与 install_artifact 仅在 default_contract 键存在时才校验,导致引导安装脚本与 loopx update 都会下载并激活该无标记预览包,随后在默认配额 CLI 暴露未定型完整的 complete_turn writer。改动后,凡是在激活或更新解析路径选择 channel 为 main 的描述符,即使缺少 default_contract,也会在下载任何归档字节之前被统一拦截,而只读历史元数据校验和既有 stable 旧版发行版安装保持兼容。

对无 default_contract 或声明不合格 default_contract 的 main 预览(无论移动标签 main 还是固定提交 SHA),loopx update check 与 update plan 会返回 target_status=blocked 与 apply_supported=false,update apply 与独立引导脚本会在下载压缩包或触发本地安装器之前失败退出,同时不改写已有软链接与下载缓存;历史元数据读取与元数据一致的旧版 stable 发行版仍可正常完成校验与安装。

本 PR 不改变 C1 complete_turn 默认切换的资格门,不修改已发布的远端 runtime-main 资产内容,不替显式 --source/--archive-url 开发者源码构建路径或 pip/pipx/源码检出分支增加预览拦截,也不在本 PR 中部署 GitHub Pages 导出产物或扩展非 macOS 平台的实机安装覆盖。

从工程必要性来看,仅仅依靠 PR #9018 修补发布端无法阻断早已发布到 runtime-main 的历史无标记预览描述符;若不做消费者侧激活校验,任何运行 loopx update apply --ref main 或公开引导安装脚本的机器仍会静默拉取并激活不合格运行时,使默认配额接口在未满足 C1 单会话成果与全成本门槛前提前切换。

改动思路 / Approach

把激活门控放回既有的元数据边界 validate_manifest 与 resolve_artifact(通过显式参数 for_activation 控制),由 CLI 目标解析 prepare_target、直调入口 install_artifact 以及 Pages 引导脚本 main 共同复用,避免新增平行开关、旁路缓存或第二套契约校验器;历史元数据读取保留 for_activation=False 默认兼容,已发布的旧版 stable 发行版在归档 runtime-artifact.json 与描述符一致时继续放行。

当前 PR 只收口消费者侧的运行时快照激活门控(update_artifact.py、update_source.py 及其单测与 release-readiness.md 说明),与已合入的发布端探测 PR #9018 形成闭环;Pages 站点的构建发布与 Linux/Windows 实机引导运行留待现有发布流水线推进。

控制流与入口收口对比如下(基于精确提交 6a9894c6909da64c97f4da39ad15ee343b344514 的源码走读与基线/HEAD 双版本执行对照):

场景 / 调用路径 for_activation 描述符 channel / default_contract 归档 runtime-artifact.json 基线 4a0188c1ca 当前 HEAD 6a9894c690
历史只读校验 validate_manifest(v) False(默认) main(缺 default_contract) 未读取 允许读取 允许读取(兼容保留)
CLI update check/plan/apply --ref main 或 --ref <SHA> True(prepare_target) main(缺 default_contract) 不进入下载 解析成功并允许 apply target_status=blocked,apply_supported=false
引导脚本 update-artifact.py(main 或 <SHA>) True(main()) main(缺 default_contract) 不进入下载 尝试下载激活 下载前报错退出(rc=1),缓存与软链不变
直调 install_artifact 传入缓存 plan True main(缺 default_contract) 不进入下载 下载并激活 下载前抛 ValueError,不触达安装器
旧版 stable 发行版(如 2.3.0) True stable(缺 default_contract) 同样无 default_contract 允许安装 允许安装(保持旧版可用)
旧版 stable 描述符伪装新归档 True stable(缺 default_contract) 含 complete_turn 忽略归档内契约差异并激活 解压校验拦截:default contract disagrees
不支持或缺失 channel 的激活请求 True channel 非 main/stable 不进入下载 未拦截未知 channel 下载前拒绝:no supported installation channel

所有持久化或远端元数据均未新增字段、开关或状态机枚举;for_activation 仅是激活路径传入 validate_manifest 与 resolve_artifact 的调用期布尔参数,可逆性与隔离边界清晰。

具体改动 / Changes

对照已接受规范文档 docs/product/release-readiness.md(评审基准提交 4a0188c1ca1b6e33a11a7e31ddb56315bc1cdd46 第 49–63 行与第 284–308 行),各验收条目的映射如下(本次 PR 同时在 docs/product/release-readiness.md 第 64–75 行以中英双语补充了 main 预览快照需携带受支持 default_contract 的说明,与原第 284–308 行契约一致):

  • RR-1(更新入口在下载或激活前拒绝未获资格的默认契约声明):implemented —— loopx/cli_commands/update_artifact.py 的 validate_manifest(..., for_activation=True)、resolve_artifact(..., for_activation=True)、install_artifact、main() 与 loopx/cli_commands/update_source.py 的 prepare_target 共同覆盖 CLI、独立引导与直调执行边界,并在下载前中止。
  • RR-2(校验归档内 runtime-artifact.json 的 default_contract 与发行元数据一致):implemented —— install_artifact 将比对条件从仅在 manifest 含该键时检查收紧为 identity.get("default_contract") != manifest.get("default_contract"),防止无标记 stable 描述符夹带含 complete_turn 的归档。
  • RR-3(保留历史 v1 描述符只读兼容性,以及元数据匹配的旧版 stable 安装路径):implemented —— validate_manifest 与 resolve_artifact 默认 for_activation=False,且 for_activation=True 仅对 channel == "main" 强制要求 default_contract,stable 无该字段且与归档一致时仍可安装。
  • RR-4(保留既有 --rollback 回退、--source 源码构建及 python_distribution / source_checkout 既有所有者路径):implemented —— build_rollback_plan、execute_rollback_plan、distribution == "source" 与非 loopx_release_snapshot 所有者分支均未受影响。

关键代码讲解

  1. loopx/cli_commands/update_artifact.py:117 — validate_manifest(value, *, revision=None, for_activation=False)
    • 新增 for_activation 关键字参数:当 for_activation=True 时,先校验 channel in ("main", "stable"),并在 "default_contract" in value or (for_activation and channel == "main") 时调用 validate_default_contract(value.get("default_contract"))。历史只读调用保持 for_activation=False,因此无该字段的旧预览元数据仍可被反序列化或审计,而一旦进入安装激活流程就必须持有合法的 PUBLIC_DEFAULT_CONTRACT。
  2. loopx/cli_commands/update_artifact.py:147 — resolve_artifact(repo, ref, *, for_activation=False)
    • 将 for_activation 透传给 validate_manifest;保留既有 URL 路由(stable、main、40 位 SHA 的 runtime-main-{ref} 及其仅在 404 时回退旧 runtime-main、版本 tag v*)及 ref in {"main", "stable"} 的 channel 一致性校验。
  3. loopx/cli_commands/update_artifact.py:415 — install_artifact(manifest, *, env, timeout_seconds, progress=...)
    • 在 download_artifact 之前调用 validate_manifest(manifest, for_activation=True),阻断任何跳过 resolve_artifact(例如复用缓存或预先构造的 update plan)的直接安装调用;并在解压 runtime-artifact.json 后把比对收紧为 identity.get("default_contract") != manifest.get("default_contract"),从而同步拦截“旧 stable 描述符指向带 complete_turn 归档”的错配情形。
  4. loopx/cli_commands/update_artifact.py:439 — main()
    • 公开引导脚本入口(由 standalone_source() 导出至 Pages update-artifact.py)在检查本地 loopx 所有权之后、调用 target_direction 与 install_artifact 之前,显式以 for_activation=True 调用 resolve_artifact,确保 curl 引导在无已安装 loopx 包的纯标准库环境下同样提前拒绝未达标预览。
  5. loopx/cli_commands/update_source.py:16 — prepare_target(payload, *, freshness, resolve_remote, allow_downgrade)
    • 当 install_lifecycle.owner == "loopx_release_snapshot" 且 source.distribution == "runtime" 时,第 26 行以 for_activation=True 调用 resolve_artifact。捕获到的 ValueError 会写入 reason 并触发第 63–70 行的统一阻塞投影:source.target_status = "blocked"、plan.apply_supported = false、plan.mutates_release_install = false、next_action.kind = "review_update_target",且即使传入 --allow-downgrade 也不会绕过。

测试同步更新情况:tests/test_update_artifact.py(+22/-5)新增缺标记 main 预览仍可读但在 install_artifact 下载前中止的测试,以及 stable 与 main 双通道的 runtime-artifact.json 契约不一致拦截测试,并校验 main() 传入 for_activation=True;tests/test_update_operation.py(+25/-2)新增参数化测试验证 ref="main" 与 ref="2"*40 在 allow_downgrade=True 下依然在 build_update_plan 阶段被阻塞。

对主干的风险 / Risks

综合失败路径推演、非适用边界检查与实测验证,本次改动对 main 回归风险可控,无 P0/P1 阻断项:

  • 非激活路径与兼容性:未触及 python_package_manager(pip/pipx)、source_checkout、--source 源码构建以及 loopx update --rollback。validate_manifest 默认保持 for_activation=False,且我们在 tests/architecture/test_content_digest_single_owner.py 验证了 standalone_source() 与单点摘要绑定未被破坏(244/244 通过)。
  • 已执行的实测验证:
    • 变更聚焦测试与更新激活测试:pytest -q -rs tests/test_update_artifact.py tests/test_update_operation.py 68 passed(0 skipped);tests/test_self_upgrade.py、tests/test_self_update_runtime_activation.py、tests/test_runtime_snapshot_publication.py、tests/test_archive_installer_commit_response.py 156 passed, 5 skipped(2 项需显式 LOOPX_TEST_NATIVE_APP_RESTART=1 的 macOS AppKit 测试、3 项仅限 Windows 原生环境的测试,均属预期环境跳过)。
    • 静态与边界检查:ruff check(4 个变更 Python 文件)PASS;仓级 mypy(17 个配置受控文件)PASS;mypy --follow-imports=silent 检查两份变更源码仅见既有未标注预存行报错,本 PR 变更行 0 新增报错;loopx check --scan-path ... 5 文件公开/隐私边界扫描 PASS(0 errors, 0 warnings);scripts/check_rfc_bilingual.py 与 git diff --check PASS。
    • 双版本反事实与隔离 python -I 引导对照:已实测基线 4a0188c1ca 会接受无 default_contract 的 main / <SHA> 预览并放行带 complete_turn 的 stable 归档,而精确提交 6a9894c690 全部在下载或安装器调用前拦截;同时实测 standalone_source() 导出脚本在 python -I(无 loopx 包)下会拒绝无标记 main 与 <SHA>(downloads=[], installs=0, rc=1)并成功安装匹配的旧版 stable 包(installs=1, rc=0)。
    • loopx canary premerge --from-git-diff --git-diff-base origin/main:在独立 worktree 安装 npm ci --ignore-scripts 依赖后,direct checks 4/4 PASS、python_compile PASS、risk_profile_smokes 8/8 PASS、public_boundary PASS、catalog_canaries 9/10 PASS(含 install-local-smoke、loopx-update-smoke、semantic-vocabulary-drift-smoke、cli-output-budget-regression-smoke);唯一失败的 control-plane-maintainability-ratchet-smoke.py --format=json 为 advisory_failure,已在不可变基线 4a0188c1ca 复现完全一致的预存报错签名(oversized_decision_function:loopx.control_plane.work_items.interaction_contract:_admitted_interaction_next_cli_actions,statements=96 > 90,本 PR 未修改该文件)。
  • 非阻断性观察与遗留项:
    1. resolve_artifact 在 ref 为 40 位提交 SHA 时仅从 runtime-main-{ref} 或 runtime-main 拉取元数据,但第 171 行仅校验了 ref in {"main", "stable"} 的 channel == ref,未对固定 SHA 显式断言 channel == "main";尽管现有 runtime-snapshots.yml 发布器固定写入 channel="main" 且 install_artifact 仍会核对归档内 default_contract,后续可考虑在 SHA.fullmatch(ref) 分支补强 channel == "main" 检查。
    2. tests/test_update_artifact.py 的 test_exported_bootstrap_validates_metadata_without_an_installed_package 暂未直接覆盖导出脚本中的 for_activation=True 与匹配的旧版 stable 正向安装用例(本次审查已通过独立 python -I 探针补足验证);此外 PR #9036 同样在 docs/product/release-readiness.md 第 64 行附近相邻位置增补 pip/pipx 说明,合入顺序先后时需留意常规文本上下文合并。

我的整体评价 / Verdict

  • 长程与用户体验影响:long_horizon 为 improved,防止无标记历史预览包在维护者或自动化执行 update apply --ref main 时将运行环境悄悄切换到未达标的 complete_turn writer;user_experience 为 improved,update check/plan/apply 与独立引导在下载前即给出明确的资格阻塞提示且保留旧版 stable 与回退可用。视觉评审结论:本次改动仅涉及 CLI 更新计划(update_artifact.py / update_source.py)、独立引导脚本导出边界与 release-readiness.md 文档说明,不修改任何渲染 UI、前端页面或桌面视图(已检查 diff 的 5 个变更文件)。,未验证范围(unverified_scope):none。
  • 代码体量、兼容性与架构评价:生产改动仅 +18/-11 行,测试 +47/-7 行,文档 +12 行,属于最小且高度内聚的修复(code_volume=necessary、change_proportionality=proportionate、compatibility_assessment=retain、architecture_assessment=retain)。机制均落在既有的 update_artifact.py 与 update_source.py 所有者内,未引入新词汇或平行状态(semantic_alignment=aligned,candidate_decision=reuse_existing,复用 PUBLIC_DEFAULT_CONTRACT 与 loopx_runtime_artifact_v1)。
  • 残留风险与待完成验证:Pages 工作流重新导出 update-artifact.py 后的线上部署与 Linux/Windows 平台实机执行仍需依赖现有 CI/发布通道完成;精确提交 6a9894c6909da64c97f4da39ad15ee343b344514 仍处于最新状态且可安全批准合入(本审查按指令保持 PR 开启,不执行合并)。

English Verdict: APPROVE — exact head 6a9894c closes the prebuilt main-preview adoption gap before archive download while preserving historical reads, legacy stable installs, and rollback paths; no blocking findings remain (targeted update/activation pytest, architecture checks, ruff, mypy, public boundary check, and counterfactual probes pass; pre-existing maintainability ratchet failure verified unchanged on base).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant